isp-status

Documents

isp-status is a purpose-built internet uplink monitoring appliance designed to answer one question clearly and honestly:

What is the real state of internet connectivity right now, and how has it behaved recently?

It is not a dashboard platform.
It is not a billing tool.
It is not a traffic analyzer.

It is an operational truth surface.

Core Principles

  • Clarity over cleverness
  • Signal over noise
  • Data-plane truth over protocol theory
  • Separation of concerns (routing, uplinks, BGP)
  • No external dependencies

Architecture Overview

Lightweight Appliance Design

  • Designed for VM environments (ESXi validated)
  • Ubuntu minimal install tested
  • SQLite authoritative backend
  • No external cloud services
  • No agent framework
  • No telemetry pipelines

Recommended baseline:

  • 2 vCPU
  • 2 GB RAM
  • 240 GB storage (more if long retention required)

Uplink Monitoring Model

Each uplink is treated as a dedicated, forced-interface test path.

Forced Interface Probing

All probes are bound to the specific NIC:

  • ICMP via ping -I
  • HTTPS via curl --interface

This prevents route ambiguity and ensures true per-uplink measurement.

3-State Historical Model

Each minute is classified as:

State Meaning
UP Internet reachable and healthy
DEGRADED Internet reachable but impaired
DOWN Internet unusable

The system records the worst state observed within each minute to prevent false optimism.

NAT-Aware Gateway Logic

Not all uplinks behave the same.

  • ISP-facing links require gateway reachability.
  • NAT/LAN uplinks may ignore gateway ICMP if outbound traffic works.

This prevents false “DOWN” classifications in real-world NAT environments.

Live View

60-Minute Operational Graph

  • 1 data point per minute
  • Per-uplink view
  • Data-plane usability only
  • BGP intentionally excluded

The graph answers:

“Was this link usable for outbound internet traffic at this minute?”

It emphasizes patterns over snapshots.

Historical Analysis

Long-range history is rolled up into 5-minute buckets.

Supported ranges:

  • 24 hours
  • 72 hours
  • 7 days
  • 30 days
  • 90 days

Includes:

  • Per-state minute counts
  • Percentage summaries
  • Daily breakdowns
  • CSV export capability
  • Deterministic padded graph rendering

Internet Validation Model

Each uplink performs dual outbound testing:

ICMP Targets

  • 1.1.1.1
  • 8.8.8.8

HTTPS Targets

  • 1.1.1.1
  • Google
  • Dedicated anti-cache endpoint

Either protocol succeeding indicates partial usability.

This avoids:

  • ICMP-only false negatives
  • HTTPS-only false positives

Canary Integrity Endpoint

A nocache.php endpoint is used as a validation probe.

It exists to answer:

“Is this request reaching the real internet right now, without caching, rewriting, or interception?”

It is not used in uptime rollups.
It is a diagnostic integrity probe, not a stability metric.

Health & Integrity Monitoring

isp-status monitors itself.

The internal health system validates:

  • System uptime
  • Load averages
  • RAM usage
  • Disk utilization
  • SQLite database status
  • File permissions
  • History freshness
  • Missing data detection
  • Largest historical gap detection

If the monitoring system degrades, it is visible.

App-Down Protection

If the Flask application becomes unreachable:

  • Synthetic “System Unresponsive” points are injected into history.
  • Graphs do not silently gap.
  • Monitoring integrity is preserved.

Evidence & Forensics

Designed for operational environments.

Downloadable Bundles (direct LAN only)

  • Systemd unit definitions
  • Service status
  • Journal logs
  • Troubleshooting log
  • Application source snapshot
  • Static files and templates
  • Optional SQLite database

This allows:

  • Rapid escalation
  • Offline review
  • Evidence preservation
  • Reproducibility

Health Update Bundles (direct LAN only)

Operator actions on /health are only available from the direct LAN admin URL: http://172.16.198.26:8080/health.

When preparing a ZIP for /health update import:

  • Include file members only.
  • Use forward-slash paths under app/, for example app/templates/health.html and app/static/css/app.css.
  • Do not include directory entries such as app/static/ or app/templates/; the importer rejects them as non-allowed app paths.
  • Be careful with PowerShell Compress-Archive when zipping a directory, because it can include directory members. Verify the archive with tar -tf bundle.zip before upload.

Control Plane Separation (BGP)

BGP is displayed separately from uplink usability.

Why?

  • BGP can be UP while traffic is broken.
  • Traffic can briefly function while BGP is DOWN.
  • Mixing them creates false conclusions.

isp-status separates control-plane visibility from data-plane truth.

Reverse Proxy Friendly

Designed to sit behind:

  • Caddy
  • NGINX
  • HAProxy

Supports:

  • LAN-only internal endpoints
  • Auth-protected public views
  • IP-restricted downloads

What isp-status Is NOT

  • Not a traffic analyzer
  • Not an SLA billing engine
  • Not a packet capture tool
  • Not a performance benchmarking suite
  • Not an automation framework

It is a decision-support tool.

Operational Benefits

  • Removes the need to plug a laptop into ISP links
  • Provides objective evidence during disputes
  • Makes flapping immediately visible
  • Encourages pattern-based reasoning
  • Reduces dashboard clutter
  • Improves incident confidence

Designed to Be Trusted

isp-status intentionally avoids feature creep.

If it becomes noisy or confusing:

  • Remove complexity
  • Reduce indicators
  • Preserve clarity

We don’t ship code. We ship clarity.